PR: Native LLVM IR Generation Backend, Target ABIs, DWARF Debug Info, Optimization Pipeline & Verification Suite

Metadata

• Branch: llvm_backend
• Base Branch: main (e3e8268d32dc63147ca431f28f2f3cdf1789909c)
• Total Commits: 7 (c3770edf17 .. 7fa91abfbf)
• Total Changes: 95 files changed, +12,893 insertions, -495 deletions
• PR Type: Major Feature (feat), Architecture & Refactoring (refactor), Infrastructure & CI (ci), Tests (test), Documentation (docs)

Table of Contents

1. Executive Summary
2. Background & Motivation
3. Architectural Overview & Subsystem Deep Dive
   • 3.1 Backend Driver & Lifecycle Management
   • 3.2 Robust Error Subsystem & Non-Throwing Invariants
   • 3.3 Type System Lowering & Memory Layout
   • 3.4 Constant Evaluation & Static Initializers
   • 3.5 Declaration & Global State Lowering
   • 3.6 Statement Lowering & Control Flow
   • 3.7 Expression Lowering & Operations
   • 3.8 Target Calling Convention ABIs (SysV, AAPCS64, Win64)
   • 3.9 DWARF Debug Information Subsystem
   • 3.10 Optimization Pipeline (LLVM New PassManager)
   • 3.11 Target Machine Code Generation & Multi-Format Emission
   • 3.12 C++ Exception Handling & RTTI Dispatch
   • 3.13 GNU Inline Assembly Support
4. Front-End & Build System Integration
   • 4.1 Command-Line Options & Driver Integration
   • 4.2 Decoupling Static C-Backend Macros & Dynamic Target Layouts
   • 4.3 CMake Build Configuration & LLVM Discovery
5. Quality, Standards & Architectural Conformance
   • 5.1 Centralized [[nodiscard]] Error Enumeration
   • 5.2 Pervasive noexcept & Strict -fno-exceptions
   • 5.3 Non-Throwing Heap Allocations
   • 5.4 100% Documentation Coverage (Doxygen)
   • 5.5 100% Test & Branch Coverage Gate
6. Comprehensive Testing & Verification Framework
   • 6.1 Unit Test Suite (tests/llvm_ir_backend_tests/)
   • 6.2 Lit Test Suite (tests/lit/llvm/)
   • 6.3 Shell Integration Suites (tests/test_llvm_*.sh)
   • 6.4 GCC Torture Harness & STL Header Compilation
   • 6.5 Continuous Integration & Automated Workflows
7. Complete File-by-File Change Matrix
8. Commit History & Evolution
9. Verification Guide & Instructions for Reviewers

1. Executive Summary

This pull request implements a native LLVM Intermediate Representation (IR) generation backend (llvm_gen_be) for the EDG C/C++ Front End (cpfe).

Prior to this pull request, the EDG compiler in this repository lowered its internal Intermediate Language (IL) primarily through C source code generation (c_gen_be) or C++ source code generation (cp_gen_be), relying on downstream compilers to emit machine code. This pull request introduces direct, high-fidelity lowering from EDG IL directly into LLVM IR, enabling cpfe to interface natively with the LLVM ecosystem without the intermediate textual C emission step.

Key Capabilities Introduced

• Multi-Format Code Emission: Emits human-readable LLVM IR text (.ll), binary bitcode (.bc), native target assembly (.s), and relocatable object files (.o / .obj) directly via LLVM's TargetMachine and MC layers.
• Full Itanium C++ ABI & Exception Handling: Lowers Itanium C++ personality routines (__gxx_personality_v0), landing pads, exception allocation/throw (__cxa_allocate_exception, __cxa_throw), rethrow, typeid matching (llvm.eh.typeid.for), and RTTI dispatch.
• Architectural Calling Conventions: Implements target ABI argument and return classification for:
  • System V AMD64 ABI (Eightbyte classification across INTEGER, SSE, SSEUP, X87, X87UP, COMPLEX_X87, and MEMORY, struct splitting, and sret).
  • ARM64 AAPCS64 ABI (General registers, FP/SIMD registers, Homogeneous Floating-point Aggregates [HFA] / Homogeneous Short-Vector Aggregates [HVA], reference passing, and sret).
  • Microsoft Windows x64 ABI (Scalar registers, power-of-two composite registers [1, 2, 4, 8 bytes], indirect caller-allocated copy pointers, and sret).
• Comprehensive DWARF Debug Information: Uses LLVM's DIBuilder to emit DWARF metadata (DICompileUnit, DISubprogram, DILexicalBlock, DILocation, primitive/composite DIType descriptors, and @llvm.dbg.declare / @llvm.dbg.value for variables).
• Optimization Pipeline Integration: Integrates LLVM's New Pass Manager (PassBuilder) with full support for optimization levels O0, O1, O2, O3, Os, and Oz, function inlining, and SLP/Loop vectorization.
• GNU Inline Assembly: Translates EDG assembly constructs (stmk_asm) into llvm::InlineAsm, supporting operand constraint strings, memory operands (*), register clobber lists, and multi-output struct extractions via extractvalue.
• Standards & Code Quality Compliance:
  • Standardized on C++17 with strict -fno-exceptions.
  • Pervasive noexcept decoration across 100% of backend functions.
  • Centralized [[nodiscard]] llvm_gen_be_error_t error enumeration with mandatory bubbling (0 ignored error returns).
  • Allocation safety with non-throwing new (std::nothrow) and out_of_memory error handling.
  • 100% Doxygen documentation coverage across all files, structs, members, enums, functions, parameters, and return codes (configured via Doxyfile.llvm_be).
  • 100% function, line, and branch test coverage validated via CI (.github/workflows/llvm_be_coverage.yml).

2. Background & Motivation

The EDG front end parses C and C++ source code into a detailed, type-annotated abstract Intermediate Language (IL). Historically, EDG deployments frequently translated this IL back into high-level C code, which was subsequently compiled with a host C compiler (such as GCC, Clang, or MSVC). While portable, this model introduces several drawbacks:

1. Compilation Overhead: Re-emitting source code, parsing it again in a separate compiler, and reconstructing semantic trees introduces substantial compilation time latency.
2. Type & Optimization Fidelity Loss: Lowering high-level constructs into C source often obfuscates original type layouts, lifetime boundaries, aliasing guarantees (noalias/restrict), and exact calling conventions.
3. Toolchain Fragility: Discrepancies between host C compiler dialects and the generated C dialect can result in subtle ABI mismatches or compiler warnings.

By implementing a direct LLVM IR generator inside EDG:

• The compiler directly emits strongly-typed LLVM IR matching the host target triple and data layout.
• The front end can directly invoke LLVM's state-of-the-art optimization pipelines (LLVM New Pass Manager) and code generation infrastructure.
• Object code and assembly can be produced in a single invocation of cpfe, turning EDG into a fully self-contained, end-to-end compiler.

3. Architectural Overview & Subsystem Deep Dive

The backend architecture is located under src/llvm_gen_be* and organized into dedicated, modular subsystems:

src/
├── llvm_gen_be.h / .cpp             ── Driver entry point, module lifecycle, file emission
├── llvm_gen_be_internal.h          ── Persistent backend state (LLVMBackendState), caches
├── llvm_gen_be_error.h / .cpp       ── Centralized [[nodiscard]] error enum & error context
├── llvm_gen_be_type.h / .cpp        ── Type lowering: primitives, composites, arrays, opaque ptrs
├── llvm_gen_be_const.h / .cpp       ── Constant evaluation: integers, APFloat, strings, aggregates
├── llvm_gen_be_decl.cpp             ── Declarations, functions, allocas, globals, TLS, ctors/dtors
├── llvm_gen_be_stmt.cpp             ── Statements: control flow, loops, switch, goto, asm, EH
├── llvm_gen_be_expr.h / .cpp        ── Expressions: arithmetic, bitwise, GEP, casts, calls, throws
├── llvm_gen_be_abi_sysv_x86_64.*    ── System V AMD64 ABI classification & variadics
├── llvm_gen_be_abi_aapcs64.*        ── ARM64 AAPCS64 ABI classification & HFA/HVA
├── llvm_gen_be_abi_win64.*          ── Microsoft Windows x64 ABI classification & variadics
├── llvm_gen_be_debug.h / .cpp       ── DWARF debug builder lifecycle & compile unit
├── llvm_gen_be_debug_scopes.cpp     ── Lexical block scopes, subprograms, variable locations
├── llvm_gen_be_debug_types.cpp      ── DWARF type descriptors for primitives & composites
├── llvm_gen_be_opt.h / .cpp         ── PassBuilder integration (O0-O3, Os, Oz, vectorization)
└── llvm_gen_be_codegen.h / .cpp     ── TargetMachine initialization & direct MC emission (.s, .o)

3.1 Backend Driver & Lifecycle Management

• Entry Points:
  • llvm_gen_be(): Main entry point called by cfe.c during frontend execution.
  • back_end(): Standard EDG backend hook, guarded in c_gen_be.h/cp_gen_be.h and routed to llvm_gen_be().
  • llvm_gen_be_cleanup(): Clean teardown called from fe_wrapup.c, releasing AST maps, symbol tables, and LLVM context structures.
• State Management (LLVMBackendState):
  Encapsulates the llvm::LLVMContext, llvm::Module, llvm::IRBuilder<>, llvm_gen_be_debug_state_t, symbol lookup tables, type cache, VLA stack markers, and landing pad stacks.
• Dynamic Data Layout & Triple Resolution:
  Constructs target-accurate DataLayout strings at runtime using EDG target configuration parameters (targ_char_bit, targ_sizeof_pointer, targ_sizeof_int, targ_sizeof_double, etc.), avoiding hardcoded host assumptions.
• Verification:
  Automatically executes llvm::verifyModule() and llvm::verifyFunction(), mapping verification diagnostics to EDG internal diagnostics.

3.2 Robust Error Subsystem & Non-Throwing Invariants

• Centralized Enumeration:
  enum class [[nodiscard]] llvm_gen_be_error_t : int defines:
  • ok: Success.
  • invalid_argument: Null pointer or invalid parameter passed.
  • out_of_memory: Allocation failed.
  • unsupported_type, unsupported_expr, unsupported_stmt: Unimplemented or unexpected IL node.
  • abi_classification_failed: Calling convention mismatch.
  • di_metadata_failure: Debug metadata generation error.
  • pass_pipeline_failure: Optimization pass manager error.
  • code_gen_failure: Machine code emission failure.
  • verification_failure: LLVM IR verifier rejected module/function.
  • io_error: Output stream failure.
• Persistent Error Context (llvm_gen_be_error_context_t):
  Threaded directly through be_state->err_context, storing the filename, line, column, and a 512-byte formatted diagnostic message.
• Strict Out-Parameters:
  Functions return status codes and pass results via out-pointers (e.g., llvm_gen_be_error_t get_llvm_type(a_type_ptr edg_type, llvm::Type** out_type) noexcept), ensuring that every return code is checked at the call site.

3.3 Type System Lowering & Memory Layout

• Scalars & Floats:
  • Integers: i1 (bool), i8, i16, i32, i64, and i128.
  • Floating points: half / fp16 (fk_fp16, fk_float16), bfloat16 (fk_std_bfloat16), float, double, x86_fp80, and fp128.
  • C99 _Complex: Aggregate struct { elem_ty, elem_ty }.
• Opaque Pointers:
  Fully modernized for LLVM 15+ opaque pointer architecture using llvm::PointerType::getUnqual(*be_state->context).
• Aggregates & Struct Padding:
  • Packed LLVM structures with explicit byte padding arrays ([N x i8]) matching EDG field offsets (field->offset).
  • Union lowering to the largest constituent element plus trailing padding.
  • Cyclic and self-referential struct definitions resolved via named opaque structs (llvm::StructType::create()).
• Pointer-to-Member Types:
  • Pointers to member functions lowered to { ptrdiff_t, ptrdiff_t }.
  • Pointers to member data lowered to ptrdiff_t.

3.4 Constant Evaluation & Static Initializers

• Integer Constants: Handled via llvm::ConstantInt for arbitrary bit-widths.
• Floating-Point Constants: Hexadecimal APFloat string formatting via fp_to_hex_constant_string(), correctly handling positive/negative zero, subnormals, infinities, and NaNs.
• String Literals: Emits ConstantDataArray for 8-bit strings, UTF-16 strings (uint16_t[]), and UTF-32 strings (uint32_t[]), placed in private global string constants (.str).
• Label Addresses: Lowers address-of-label constants into llvm::BlockAddress::get(func, label_bb).
• Nested Aggregates: Recursively constructs llvm::ConstantStruct and llvm::ConstantArray instances.

3.5 Declaration & Global State Lowering

• Variables:
  • Global variable emission with proper linkage: ExternalLinkage, InternalLinkage (static), LinkOnceODRLinkage (inline/templates), WeakAnyLinkage.
  • Thread-Local Storage (GeneralDynamicTLSModel).
  • COMDAT group assignment.
  • Attribute support: __attribute__((section("..."))) and visibility flags (Hidden, Protected, Default).
• Routines / Functions:
  • Declaration prototypes and function definitions.
  • Attributes: NoReturn, AlwaysInline, NoInline, NoAlias (for restrict pointers).
  • Scope paging via get_scope_for_routine_definition() using read_memory_region() to guarantee routine IL is paged into memory during backend generation.
• Constructors & Destructors:
  Registers initialization functions into @llvm.global_ctors and @llvm.global_dtors with specified priority keys.

3.6 Statement Lowering & Control Flow

• Basic Statements: Expression statements (stmk_expr), return statements (stmk_return with value or void), blocks (stmk_block) with scoped alloca allocations.
• Control Flow: If/else branching, while loops, for loops, and do-while loops. Breaks and continues branch directly to destination blocks managed on be_state->break_blocks and be_state->continue_blocks.
• Switches & GNU Ranges: Emits llvm::SwitchInst, handling both individual case expressions and GNU case ranges (case low ... high:).
• Computed Gotos: Emits llvm::IndirectBrInst targeting address-taken label blocks.
• VLA Stack Management: Emits @llvm.stacksave and @llvm.stackrestore intrinsics at scope entry and exit.

3.7 Expression Lowering & Operations

• LValue vs RValue Semantics: Clear separation; implicit CreateLoad emitted when evaluating an LValue in an RValue context; preserves volatile qualifiers.
• Arithmetic & Logic: Signed/unsigned integer operations, floating-point operations, bitwise operations, signed/unsigned comparisons (icmp, fcmp).
• Short-Circuiting Logic: Logical AND (&&) and OR (||) lower to short-circuit conditional branches with result llvm::PHINodes.
• Ternary Operator (?:): Lowered via conditional branches and PHI merging.
• Memory References: GEP calculations for array indices and struct field offsets.
• Aggregate Copies: Optimizes large struct/class assignments (eok_assign) by emitting @llvm.memcpy calls.
• Bitfield Manipulation:
  • Reads: Shifts right (lshr/ashr) by field->bit_offset and masks (and) with (1 << bit_size) - 1.
  • Writes: Loads container word, masks out target field bits, shifts value left, bitwise ORs new value, and stores back.

3.8 Target Calling Convention ABIs

Implemented in dedicated modules for target-specific parameter passing and return rules:

• System V AMD64 ABI (src/llvm_gen_be_abi_sysv_x86_64.*):
  • Eightbyte classification algorithm classifying chunks into INTEGER, SSE, SSEUP, X87, X87UP, COMPLEX_X87, and MEMORY.
  • Small aggregate splitting into multiple registers (e.g., pairs of i64 or double).
  • Large aggregate memory passing (byval).
  • Structural return (sret) for types exceeding 16 bytes or classified as MEMORY.
  • Variadic function lowering (va_start, va_arg, va_copy, va_end).
• ARM64 AAPCS64 ABI (src/llvm_gen_be_abi_aapcs64.*):
  • General purpose register allocation (X0–X7).
  • SIMD/FP register allocation (V0–V7).
  • Homogeneous Floating-point Aggregates (HFA) and Homogeneous Short-Vector Aggregates (HVA) detection (up to 4 identical FP/vector members passed in registers).
  • Composites exceeding 16 bytes passed indirectly by reference.
  • Sret return classification and variadic lowering.
• Microsoft Windows x64 ABI (src/llvm_gen_be_abi_win64.*):
  • Scalar arguments passed in RCX, RDX, R8, R9 or XMM0–XMM3.
  • Aggregate types of size 1, 2, 4, or 8 bytes passed directly in integer registers.
  • Aggregate types of other sizes passed indirectly via caller-allocated copy pointers.
  • Return rules and va_start lowering.

3.9 DWARF Debug Information Subsystem

• Builder Lifecycle: Managed by llvm_gen_be_debug_state_t using llvm::DIBuilder.
• Compile Unit & Scopes: Emits DICompileUnit with compile flags, host compiler version, and source filename.
• Subprograms & Lexical Blocks: Emits DISubprogram for each function definition and maintains a scope stack (push_lexical_block, pop_lexical_block) emitting nested DILexicalBlocks.
• Debug Locations: Attaches DILocation metadata to instructions matching EDG a_source_position.
• Types & Variables: Emits DIBasicType, DIDerivedType (pointers/const), DICompositeType (arrays, structs), and attaches @llvm.dbg.declare with DILocalVariable descriptors to stack allocas.

3.10 Optimization Pipeline (LLVM New PassManager)

• Integrates LLVM's PassBuilder with ModulePassManager, FunctionPassManager, and analysis managers (LoopAnalysisManager, FunctionAnalysisManager, CGSCCAnalysisManager, ModuleAnalysisManager).
• Configurable via llvm_opt_options_t supporting levels O0, O1, O2, O3, Os, and Oz.
• Enables function inlining, Loop Vectorization, and SLP Vectorization passes.

3.11 Target Machine Code Generation & Multi-Format Emission

• Initializes LLVM target registries (initialize_llvm_targets).
• Resolves target triples for Linux, macOS, and Windows on x86_64 and AArch64.
• Direct output generation via emit_machine_code_to_file():
  • LLVM IR Text: .ll (via raw_fd_ostream)
  • LLVM Bitcode: .bc (via WriteBitcodeToFile)
  • Native Assembly: .s (via TargetMachine::addPassesToEmitFile with CodeGenFileType::AssemblyFile)
  • Relocatable Object Code: .o / .obj (via TargetMachine::addPassesToEmitFile with CodeGenFileType::ObjectFile)

3.12 C++ Exception Handling & RTTI Dispatch

• Emits Itanium personality routine reference (__gxx_personality_v0).
• Generates invoke instructions for function calls inside active try-blocks, targeting exception landing pads.
• Generates landingpad instructions with typeinfo clauses and cleanup flags.
• Emits catch matching blocks using llvm.eh.typeid.for and typeinfo comparisons.
• Emits runtime calls to __cxa_allocate_exception, __cxa_throw, __cxa_rethrow, __cxa_begin_catch, and __cxa_end_catch.
• Emits catch (...) (catch-all) and resume instructions for unhandled exceptions.

3.13 GNU Inline Assembly Support

• Lowers stmk_asm statements to llvm::InlineAsm.
• Parses input and output constraints, memory constraints (*), and clobber lists (named_register_names).
• Emits call instructions to inline assembly objects with hasSideEffects = true.
• Supports multiple output operands via packed struct return types and subsequent extractvalue instructions.

4. Front-End & Build System Integration

4.1 Command-Line Options & Driver Integration

Registered new CLI flags in src/cmd_line.h and src/cmd_line.c:

• --gen_llvm_file_name <file>: Emits textual LLVM IR (.ll).
• --gen_llvm_bc_file_name <file>: Emits LLVM binary bitcode (.bc).
• --gen_obj_file_name <file>: Emits native machine object file (.o / .obj).
• --gen_asm_file_name <file>: Emits native assembly file (.s).

Hooked backend execution in src/cfe.c:

#if BACK_END_IS_LLVM_GEN_BE
  llvm_gen_be();
#endif

Hooked memory cleanup in src/fe_wrapup.c:

#if BACK_END_IS_LLVM_GEN_BE
  llvm_gen_be_cleanup();
#endif

4.2 Decoupling Static C-Backend Macros & Dynamic Target Layouts

• Updated src/defines.h and src/host_envir.h to define BACK_END_IS_LLVM_GEN_BE and decouple backend configurations from BACK_END_IS_C_GEN_BE assumptions.
• Guarded back_end() in src/c_gen_be.c, src/c_gen_be.h, src/cp_gen_be.c, and src/cp_gen_be.h when BACK_END_IS_LLVM_GEN_BE is active, allowing clean linking without symbol collisions.
• Decoupled C-backend layout assumptions in src/targ_def.h and src/lower_il.c.

4.3 CMake Build Configuration & LLVM Discovery

• Upgraded C++ standard to C++17 (set(CMAKE_CXX_STANDARD 17)) across src/CMakeLists.txt and dev_tools/CMakeLists.txt.
• Added ENABLE_LLVM_BACKEND cache option (set(ENABLE_LLVM_BACKEND FALSE CACHE BOOL ...)).
• Implemented robust LLVM package detection with Homebrew LLVM path discovery on macOS:

if(APPLE)
  find_program(BREW_EXECUTABLE brew)
  if(BREW_EXECUTABLE)
    execute_process(
      COMMAND ${BREW_EXECUTABLE} --prefix llvm
      OUTPUT_VARIABLE BREW_LLVM_PREFIX
      OUTPUT_STRIP_TRAILING_WHITESPACE
    )
    if(EXISTS "${BREW_LLVM_PREFIX}")
      list(APPEND CMAKE_PREFIX_PATH "${BREW_LLVM_PREFIX}")
      set(LLVM_DIR "${BREW_LLVM_PREFIX}/lib/cmake/llvm" CACHE PATH "LLVM config dir" FORCE)
    endif()
  endif()
endif()
find_package(LLVM CONFIG)

• Added LLVM include directories and library links to src/cmake/cpfe/CMakeLists.txt and src/cmake/cpfe-cp/CMakeLists.txt.
• Linked tests in tests/CMakeLists.txt with LLVM components: Core, Support, Target, BitWriter, Analysis, Passes, MC, MCParser, TargetParser, AsmPrinter, AsmParser.

5. Quality, Standards & Architectural Conformance

This pull request strictly satisfies all project-wide quality standards and mandates:

5.1 Centralized [[nodiscard]] Error Enumeration

• Decorated typedef enum class [[nodiscard]] llvm_gen_be_error_t : int in src/llvm_gen_be_error.h.
• Guaranteed that compiler linters enforce mandatory checking at all call sites across the entire backend.
• Zero swallowed return values or (void) casts on error functions.

5.2 Pervasive noexcept & Strict -fno-exceptions

• 100% of functions across src/llvm_gen_be*.h and src/llvm_gen_be*.cpp are decorated with noexcept.
• Zero use of C++ exception keywords (throw, catch, try).
• Compiled in strict -fno-exceptions mode.

5.3 Non-Throwing Heap Allocations

• All dynamic memory allocations throughout the backend use new (std::nothrow).
• Every allocation is followed by a null check returning llvm_gen_be_error_t::out_of_memory.

5.4 100% Documentation Coverage (Doxygen)

• Complete Doxygen coverage verified via Doxyfile.llvm_be:
  • @file and @brief / @details for every source and header file.
  • @struct / @enum / @class block for every data structure.
  • Field-level documentation comments for all struct members and enum values.
  • Function-level @brief, @details, explicit @param[in]/@param[out], and @return documenting llvm_gen_be_error_t::ok and failure modes.

5.5 100% Test & Branch Coverage Gate

• Strict 100% code coverage requirement enforced in CI (.github/workflows/llvm_be_coverage.yml and dev_tools/bin/run_coverage.sh).
• Every branch, error path, and invalid input is exercised by dedicated unit and fault-injection tests.

6. Comprehensive Testing & Verification Framework

The pull request adds an extensive, multi-tiered test infrastructure:

6.1 Unit Test Suite (tests/llvm_ir_backend_tests/)

18 dedicated C++ unit test executables verifying each subsystem in isolation:

1. error_test.cpp: Tests all llvm_gen_be_error_t enum values, string formatting, context recording, and reset behavior.
2. fault_injection_test.cpp: Injects null pointers, invalid type kinds, unsupported expressions/statements, and bad file paths across all public APIs to verify proper error propagation.
3. type_test.cpp: Tests all scalar integer types, floating-point types (bfloat16, fp16, fp80, fp128), complex numbers, arrays, VLAs, packed structs, and unions.
4. const_test.cpp: Tests integer constants, float hexadecimal conversions, string literals (8-bit, UTF-16, UTF-32), block addresses, and nested constant aggregates.
5. codegen_test.cpp: Tests target registry initialization, TargetMachine creation for multiple target triples, and emission of .ll, .bc, .s, and .o files.
6. opt_pipeline_test.cpp: Tests parsing optimization level strings and executing PassManager pipelines across O0 through O3, Os, and Oz.
7. abi_sysv_test.cpp & abi_sysv_integration_test.cpp: Tests System V AMD64 eightbyte argument classification, struct splitting, memory pass, and sret.
8. abi_aapcs64_test.cpp: Tests ARM64 argument classification, HFA/HVA aggregate detection, and reference passing.
9. abi_win64_test.cpp: Tests Microsoft Windows x64 calling convention, power-of-two composite rules, and indirect argument passing.
10. debug_init_test.cpp: Tests DWARF debug state initialization, DIBuilder setup, and cleanup.
11. debug_scope_test.cpp: Tests subprogram creation, lexical block scope stack push/pop, and location mapping.
12. debug_types_test.cpp: Tests DWARF type descriptor generation for primitives, pointers, arrays, composites, and @llvm.dbg.declare emission.
13. eh_test.cpp: Tests landing pad construction, personality routine attachment, and catch clause typeid matching.
14. asm_test.cpp: Tests inline assembly constraint parsing, register clobbers, and multiple output values.
15. goto_test.cpp: Tests labeled statements, forward/backward jumps, and computed indirect gotos.
16. test_llvm_build_config.cpp: Validates backend build configurations and feature flags.
17. test_llvm_driver_flag.cpp: Validates command-line driver flags for LLVM output files.
18. test_llvm_verifier.cpp & test_llvm_orchestrator.cpp: Orchestrates end-to-end backend lowering and verifies module consistency.

6.2 Lit Test Suite (tests/lit/llvm/)

LLVM lit tests verifying exact IR patterns using FileCheck:

• bitfield_test.c & bitfield_test.ll: Verifies bitfield read shifts/masks and write updates.
• memcpy_test.c & memcpy_test.ll: Verifies @llvm.memcpy intrinsic generation for aggregate assignment.
• sret_test.c & sret_test.ll: Verifies structural return (sret) parameter passing and calls.
• opaque_pointers.c: Verifies opaque pointer generation and typing.
• stmt_for.c: Verifies loop basic blocks, conditions, and phi nodes.
• codegen_cli_test.c: Verifies multi-format output emission (.bc, .o, .s) via CLI options.

6.3 Shell Integration Suites (tests/test_llvm_*.sh)

Automated bash test harnesses for integration testing:

• test_llvm_abi_alignment.sh: Verifies alignment constraints across struct members and function calls.
• test_llvm_control_flow.sh: Exercises loops, switches, gotos, and breaks.
• test_llvm_coverage.sh: Runs coverage verification across the backend.
• test_llvm_execution.sh: Compiles and executes emitted LLVM IR via JIT/LLI.
• test_llvm_expressions.sh: Exercises arithmetic, bitwise, logic, casts, and GEP expressions.
• test_llvm_functions.sh: Tests function definitions, calls, arguments, and return values.
• test_llvm_globals.sh: Tests global variables, linkages, and static initializers.
• test_llvm_integration.sh: End-to-end test runner for full C translation units.
• test_llvm_output_generation.sh: Verifies that .ll, .bc, .s, and .o files are generated.
• test_llvm_stl_headers.sh: Tests lowering of standard library headers.

6.4 GCC Torture Harness & STL Header Compilation

• dev_tools/bin/run_gcc_torture_llvm.py: Automated harness to execute the GCC C Torture test suite against cpfe with the LLVM backend.
• tests/test_llvm_stl_headers.sh: Validates compilation of C and C++ standard library headers.

6.5 Continuous Integration & Automated Workflows

• .github/workflows/llvm_be_coverage.yml:
  Dedicated GitHub Actions workflow running under Clang with lcov and valgrind (memcheck), enforcing strict 100% line/branch coverage.
• .github/workflows/build-and-test-ci.yml:
  Updated main CI matrix to include a coverage-llvm job building cpfe with -DENABLE_LLVM_BACKEND=TRUE -DEDG_CPFE_USE_GCOV=TRUE and validating 100% line execution.

7. Complete File-by-File Change Matrix

8. Commit History & Evolution

The pull request comprises 7 logical, incremental commits:

1. c3770edf17 - LLVM IR backend (initial pass)
   Initial scaffolding of LLVM backend driver (llvm_gen_be.h/.cpp), build system integration (ENABLE_LLVM_BACKEND), command-line flags, type translation primitives, basic expression and statement lowerings, and shell test suite.
2. b08d2a4fd9 - LLVM IR backend: implement types, control flow, ABI, expressions, and C++ tests
   Comprehensive implementation: dynamic TargetTriple/DataLayout, scoped local symbol table, LValue/RValue semantics with implicit loads, float variants, packed structs with byte padding, unions, bitfields, linkage mappings, TLS, control flow loops/switches/jumps, GEP memory references, and migration of Python test runners to native C++ executables.
3. 72e30b8274 - LLVM IR backend: implement exception handling, inline assembly, computed gotos, and test suite
   Itanium personality setup (__gxx_personality_v0), landing pads, exception throw/rethrow runtime routines (__cxa_throw, __cxa_allocate_exception), GNU inline assembly lowering (stmk_asm to llvm::InlineAsm), computed gotos (IndirectBrInst), APFloat hex conversions, and CTest integration.
4. c387283f31 - LLVM IR backend: add RTTI/EH dispatch, inline asm outputs, opaque ptr support, and verification
   Module and function verification pass (llvm::verifyFunction), typeinfo lowering with EDG mangled names, catch clause typeid dispatch (llvm.eh.typeid.for), multiple outputs in inline asm via struct returns, opaque pointer modernization, and additional lit tests.
5. 5cc528b69f - LLVM IR backend: decouple C-backend macros, dynamically resolve target layouts, and refine codegen
   Decoupled backend macros (BACK_END_IS_LLVM_GEN_BE) from C-generator assumptions, replaced static TARG_* macros with dynamic targ_* variables, guarded back_end() in c_gen_be.c/cp_gen_be.c, added IL memory paging (read_memory_region), ensured i1 conditions for conditional branches, and upgraded build to C++17.
6. e06c445859 - LLVM IR backend: implement target ABIs, DWARF debug info, code emission, and pass pipeline
   Implemented target calling convention ABIs (SysV AMD64, AAPCS64, Win64), DWARF debug metadata emission with DIBuilder (compile units, subprograms, lexical blocks, locations, and type metadata), direct TargetMachine code emission for object files (.o) and assembly (.s), LLVM New Pass Manager optimization pipeline (O0-O3, Os, Oz), centralized error subsystem (llvm_gen_be_error_t), and modularized headers.
7. 7fa91abfbf - LLVM IR backend: standardize noexcept error propagation, integrate DWARF scopes, and update test suite
   Enforced uniform [[nodiscard]] llvm_gen_be_error_t error propagation at type definition, qualified 100% of backend functions with noexcept, migrated APIs to argument-based out-parameters, persistent error context threading, DWARF scope and parameter @llvm.dbg.declare integration, guarded legacy headers, updated test suite signatures, and aligned lit test expectations.

9. Verification Guide & Instructions for Reviewers

9.1 Prerequisites

• CMake 3.19+
• Clang or GCC supporting C++17
• LLVM 14+ development libraries (llvm-dev / brew install llvm)
• Python 3 (for test harnesses)

9.2 Building the Compiler with the LLVM Backend

# Configure with LLVM backend and testing enabled
cmake -S . -B build 
  -DCMAKE_BUILD_TYPE=Debug 
  -DENABLE_LLVM_BACKEND=ON 
  -DBUILD_TESTING=ON

# Compile the cpfe front end and test targets
cmake --build build -j$(nproc 2>/dev/null || sysctl -n hw.ncpu)

9.3 Running Backend Unit Tests

All unit tests are registered with CTest and can be run directly:

cd build
ctest --output-on-failure -R "(test_llvm|abi_|error_|debug_|codegen_|opt_|type_|const_|asm_|eh_|goto_|fault_)"

9.4 Running Lit and Shell Integration Suites

# Run shell test suites
./tests/test_llvm_globals.sh
./tests/test_llvm_functions.sh
./tests/test_llvm_expressions.sh
./tests/test_llvm_control_flow.sh
./tests/test_llvm_output_generation.sh
./tests/test_llvm_abi_alignment.sh

# Run lit tests (requires llvm-lit / lit installed)
lit -v tests/lit/llvm/

9.5 Verifying LLVM IR and Code Emission Directly

Compile sample C code using cpfe with the new LLVM driver options:

cat << 'EOF' > /tmp/sample.c
int compute_sum(int a, int b) {
    return a + b;
}
EOF

# Emit textual LLVM IR (.ll)
./build/src/cpfe --c99 --edg_base_dir include_c++ 
  --gen_llvm_file_name /tmp/sample.ll /tmp/sample.c

# Inspect generated LLVM IR
cat /tmp/sample.ll

# Emit assembly (.s) and object file (.o)
./build/src/cpfe --c99 --edg_base_dir include_c++ 
  --gen_asm_file_name /tmp/sample.s 
  --gen_obj_file_name /tmp/sample.o /tmp/sample.c

# Inspect generated assembly
cat /tmp/sample.s

9.6 Generating Doxygen API Documentation

doxygen Doxyfile.llvm_be
# Open html/index.html to browse the generated documentation

NOTE: This is not intended to be merged. Just to start a conversation…